/*
 * xlog_internal.h
 *
 * PostgreSQL 写前日志内部声明
 *
 * 注意：此文件旨在包含对直接操作 XLOG 文件有用的声明，但不应被 rmgr 例程需要（用于单个记录类型的重做支持）。
 * 因此，XLogRecord typedef 和相关内容出现在 xlogrecord.h 中。
 *
 * 注意：此文件必须在前端和后端上下文中可包含，
 * 以允许像 pg_receivewal 这样的独立工具处理 WAL 文件。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/access/xlog_internal.h
 */
#ifndef XLOG_INTERNAL_H
#define XLOG_INTERNAL_H

#include "access/xlogdefs.h"
#include "access/xlogreader.h"
#include "datatype/timestamp.h"
#include "lib/stringinfo.h"
#include "pgtime.h"
#include "storage/block.h"
#include "storage/relfilenode.h"


/*
 * 每个 XLOG 文件的页面都有一个像这样的头部：
 */
#define XLOG_PAGE_MAGIC 0xD110	/* 可用作 WAL 版本指示符 */

typedef struct XLogPageHeaderData
{
	uint16		xlp_magic;		/* 正确性检查的魔法值 */
	uint16		xlp_info;		/* 标志位，见下文 */
	TimeLineID	xlp_tli;		/* 页上第一个记录的 TimeLineID */
	XLogRecPtr	xlp_pageaddr;	/* 此页的 XLOG 地址 */

	/*
	 * 当当前页面没有足够的空间放下整个记录时，我们
	 * 会继续在下一页进行。 xlp_rem_len 是来自上一页的剩余字节数；
	 * 它跟踪初始头部中的 xl_tot_len。请注意，继续数据不一定是对齐的。
	 */
	uint32		xlp_rem_len;	/* 记录的剩余数据的总长度 */
} XLogPageHeaderData;

#define SizeOfXLogShortPHD	MAXALIGN(sizeof(XLogPageHeaderData))

typedef XLogPageHeaderData *XLogPageHeader;

/*
 * 当设置了 XLP_LONG_HEADER 标志时，我们在
 * 页面头部存储额外字段。 （通常只在
 * XLOG 文件的第一页执行。）这些额外字段用于准确识别文件。
 */
typedef struct XLogLongPageHeaderData
{
	XLogPageHeaderData std;		/* 标准头部字段 */
	uint64		xlp_sysid;		/* 来自 pg_control 的系统标识符 */
	uint32		xlp_seg_size;	/* 只是作为交叉检查 */
	uint32		xlp_xlog_blcksz;	/* 只是作为交叉检查 */
} XLogLongPageHeaderData;

#define SizeOfXLogLongPHD	MAXALIGN(sizeof(XLogLongPageHeaderData))

typedef XLogLongPageHeaderData *XLogLongPageHeader;

/* 当记录跨越页面边界时，在新页面的头部设置此标志 */
#define XLP_FIRST_IS_CONTRECORD		0x0001
/* 此标志表示一个“长”的页面头部 */
#define XLP_LONG_HEADER				0x0002
/* 此标志表示从该页面开始的备份块是可选的 */
#define XLP_BKP_REMOVABLE			0x0004
/* 替换缺失的contrecord；见CreateOverwriteContrecordRecord */
#define XLP_FIRST_IS_OVERWRITE_CONTRECORD 0x0008
/* xlp_info中所有已定义的标志位（用于头部的有效性检查） */
#define XLP_ALL_FLAGS				0x000F

#define XLogPageHeaderSize(hdr)		\
	(((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)

/* wal_segment_size的范围可以从1MB到1GB */
#define WalSegMinSize 1024 * 1024
#define WalSegMaxSize 1024 * 1024 * 1024
/* 默认的最小和最大wal段数量 */
#define DEFAULT_MIN_WAL_SEGS 5
#define DEFAULT_MAX_WAL_SEGS 64

/* 检查给定的大小是否是有效的wal_segment_size */
#define IsPowerOf2(x) (x > 0 && ((x) & ((x)-1)) == 0)
#define IsValidWalSegSize(size) \
	 (IsPowerOf2(size) && \
	 ((size) >= WalSegMinSize && (size) <= WalSegMaxSize))

#define XLogSegmentsPerXLogId(wal_segsz_bytes)	\
	(UINT64CONST(0x100000000) / (wal_segsz_bytes))

#define XLogSegNoOffsetToRecPtr(segno, offset, wal_segsz_bytes, dest) \
		(dest) = (segno) * (wal_segsz_bytes) + (offset)

#define XLogSegmentOffset(xlogptr, wal_segsz_bytes)	\
	((xlogptr) & ((wal_segsz_bytes) - 1))

/*
 * 从XLogRecPtr计算段号。
 *
 * 对于XLByteToSeg，按面值进行计算。 对于XLByteToPrevSeg，
 * 边界字节被认为是在先前的段中。这适合
 * 在给定指向记录结尾的指针时决定写入哪个段，
 * 例如。
 */
#define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes) \
	logSegNo = (xlrp) / (wal_segsz_bytes)

#define XLByteToPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
	logSegNo = ((xlrp) - 1) / (wal_segsz_bytes)

/*
 * 将以兆字节为单位测量的 GUC 值转换为等效的段数。
 * 向下舍入。
 */
#define XLogMBVarToSegs(mbvar, wal_segsz_bytes) \
	((mbvar) / ((wal_segsz_bytes) / (1024 * 1024)))

/*
 * XLogRecPtr是否在特定的XLOG段内？
 *
 * 对于XLByteInSeg，按面值进行计算。 对于XLByteInPrevSeg，
 * 边界字节被认为是在先前的段中。
 */
#define XLByteInSeg(xlrp, logSegNo, wal_segsz_bytes) \
	(((xlrp) / (wal_segsz_bytes)) == (logSegNo))

#define XLByteInPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
	((((xlrp) - 1) / (wal_segsz_bytes)) == (logSegNo))

/* 检查XLogRecPtr值是否在合理范围内 */
#define XRecOffIsValid(xlrp) \
		((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)

/*
 * XLog目录和控制文件（相对于$PGDATA）
 */
#define XLOGDIR				"pg_wal"
#define XLOG_CONTROL_FILE	"global/pg_control"

/*
 * 这些宏封装了关于XLog文件
 * 名称、时间线历史文件名称和归档状态文件名称的确切布局的知识。
 */
#define MAXFNAMELEN		64

/* XLog文件名的长度 */
#define XLOG_FNAME_LEN	   24

/*
 * 生成WAL段文件名。不要在分配结果的助手
 * 函数中使用此宏。
 */
#define XLogFileName(fname, tli, logSegNo, wal_segsz_bytes)	\
	snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli,		\
			 (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))

#define XLogFileNameById(fname, tli, log, seg)	\
	snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg)

#define IsXLogFileName(fname) \
	(strlen(fname) == XLOG_FNAME_LEN && \
	 strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN)

/*
 * 带有.partial后缀的XLOG段。由pg_receivewal使用，并在
 * 归档恢复结束时使用，当我们想要归档一个WAL段但它可能尚未
 * 完整。
 */
#define IsPartialXLogFileName(fname)	\
	(strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") &&	\
	 strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&		\
	 strcmp((fname) + XLOG_FNAME_LEN, ".partial") == 0)

#define XLogFromFileName(fname, tli, logSegNo, wal_segsz_bytes)	\
	do {												\
		uint32 log;										\
		uint32 seg;										\
		sscanf(fname, "%08X%08X%08X", tli, &log, &seg); \
		*logSegNo = (uint64) log * XLogSegmentsPerXLogId(wal_segsz_bytes) + seg; \
	} while (0)

#define XLogFilePath(path, tli, logSegNo, wal_segsz_bytes)	\
	snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli,	\
			 (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))

#define TLHistoryFileName(fname, tli)	\
	snprintf(fname, MAXFNAMELEN, "%08X.history", tli)

#define IsTLHistoryFileName(fname)	\
	(strlen(fname) == 8 + strlen(".history") &&		\
	 strspn(fname, "0123456789ABCDEF") == 8 &&		\
	 strcmp((fname) + 8, ".history") == 0)

#define TLHistoryFilePath(path, tli)	\
	snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli)

#define StatusFilePath(path, xlog, suffix)	\
	snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix)

#define BackupHistoryFileName(fname, tli, logSegNo, startpoint, wal_segsz_bytes) \
	snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli, \
			 (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) (XLogSegmentOffset(startpoint, wal_segsz_bytes)))

#define IsBackupHistoryFileName(fname) \
	(strlen(fname) > XLOG_FNAME_LEN && \
	 strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
	 strcmp((fname) + strlen(fname) - strlen(".backup"), ".backup") == 0)

#define BackupHistoryFilePath(path, tli, logSegNo, startpoint, wal_segsz_bytes)	\
	snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli, \
			 (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
			 (uint32) (XLogSegmentOffset((startpoint), wal_segsz_bytes)))

/*
 * 当我们检测到对Hot Standby重要的一个参数发生变化时记录的信息。
 */
typedef struct xl_parameter_change
{
	int			MaxConnections;
	int			max_worker_processes;
	int			max_wal_senders;
	int			max_prepared_xacts;
	int			max_locks_per_xact;
	int			wal_level;
	bool		wal_log_hints;
	bool		track_commit_timestamp;
} xl_parameter_change;

/* 日志恢复点 */
typedef struct xl_restore_point
{
	TimestampTz rp_time;
	char		rp_name[MAXFNAMELEN];
} xl_restore_point;

/* 覆盖先前的contrecord */
typedef struct xl_overwrite_contrecord
{
	XLogRecPtr	overwritten_lsn;
	TimestampTz overwrite_time;
} xl_overwrite_contrecord;

/* 恢复结束标记，当我们不执行END_OF_RECOVERY检查点时 */
typedef struct xl_end_of_recovery
{
	TimestampTz end_time;
	TimeLineID	ThisTimeLineID; /* new TLI */
	TimeLineID	PrevTimeLineID; /* 我们从中分叉的先前TLI */
} xl_end_of_recovery;

/*
 * xloginsert.c中的函数构造一个XLogRecData结构的链
 * 以表示最终的WAL记录。
 */
typedef struct XLogRecData
{
	struct XLogRecData *next;	/* 链中的下一个结构，或NULL */
	char	   *data;			/* 要包括的rmgr数据的起始位置 */
	uint32		len;			/* 包含的rmgr数据长度 */
} XLogRecData;

/*
 * 恢复目标操作。
 */
typedef enum
{
	RECOVERY_TARGET_ACTION_PAUSE,
	RECOVERY_TARGET_ACTION_PROMOTE,
	RECOVERY_TARGET_ACTION_SHUTDOWN
}			RecoveryTargetAction;

struct LogicalDecodingContext;
struct XLogRecordBuffer;

/*
 * 资源管理器的方法表。
 *
 * 此结构必须与rmgr.c中的PG_RMGR定义保持同步。
 *
 * rm_identify必须根据xl_info返回记录的名称（不参考rmid）。例如，XLOG_BTREE_VACUUM将被命名为
 * "VACUUM"。然后可以调用rm_desc以获取记录的其他详细信息（如果可用，例如最后一个块）。
 *
 * rm_mask接收资源管理器修改的页面作为输入，并屏蔽掉不应被wal_consistency_checking标记的位。
 *
 * RmgrTable[]由RmgrId值索引（参见rmgrlist.h）。如果rm_name为
 * NULL，则对应的RmgrTable条目被视为无效。
 */
typedef struct RmgrData
{
	const char *rm_name;
	void		(*rm_redo) (XLogReaderState *record);
	void		(*rm_desc) (StringInfo buf, XLogReaderState *record);
	const char *(*rm_identify) (uint8 info);
	void		(*rm_startup) (void);
	void		(*rm_cleanup) (void);
	void		(*rm_mask) (char *pagedata, BlockNumber blkno);
	void		(*rm_decode) (struct LogicalDecodingContext *ctx,
							  struct XLogRecordBuffer *buf);
} RmgrData;

extern PGDLLIMPORT RmgrData RmgrTable[];
extern void RmgrStartup(void);
extern void RmgrCleanup(void);
extern void RmgrNotFound(RmgrId rmid);
extern void RegisterCustomRmgr(RmgrId rmid, RmgrData *rmgr);

#ifndef FRONTEND
static inline bool
RmgrIdExists(RmgrId rmid)
{
	return RmgrTable[rmid].rm_name != NULL;
}

static inline RmgrData
GetRmgr(RmgrId rmid)
{
	if (unlikely(!RmgrIdExists(rmid)))
		RmgrNotFound(rmid);
	return RmgrTable[rmid];
}
#endif

/*
 * 导出以支持从检查点切换的xlog
 */
extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);

extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);

extern void XLogRecGetBlockRefInfo(XLogReaderState *record, bool pretty,
								   bool detailed_format, StringInfo buf,
								   uint32 *fpi_len);

/*
 * 导出用于timeline.c和xlogarchive.c中的函数。仅在启动过程中有效。
 */
extern PGDLLIMPORT bool ArchiveRecoveryRequested;
extern PGDLLIMPORT bool InArchiveRecovery;
extern PGDLLIMPORT bool StandbyMode;
extern PGDLLIMPORT char *recoveryRestoreCommand;

#endif							/* XLOG_INTERNAL_H */
